Atari Mega Archive 1/Atari Mega Archive - Volume 1.iso/program/progem.arc/gem4.asc

Text File | 1987-10-10 | 18KB | 336 lines

                       **Professional GEM**
                           by Tim Oren

                             11/7/85


   Welcome to the fourth installment of ST PRO GEM.  We are about to
delve into the mysteries of GEM resource structure, and then use this
knowledge to create some useful utilities for handling dialogs.  As
with the past columns, there is once again a download file.  You will
find it under the name GEMCL4.C in the ATARI 16-bit Forum (GO PCS-58).

   The first and largest part of the download contains a C image of a
sample resource file.  To create this listing, I used the GEM
Resource  Construction Set to create a dummy resource with three
dialogs including examples of all object types, then enabled the C
output option and saved  the resource.  If you have access to a copy
of RCS, I suggest that you  create your own listing in order to get a
feel for the results.  Then, using  either listing as a roadmap to
the resource, you can follow along as  we enter...

   A MAZE OF TWISTY LITTLE PASSAGES.  While a GEM resource is loaded
as a block of binary information, it is actually composed of a number
of different data structures.  These structures are linked together
in a rather tangled hierarchy.  Our first job is to map this linkage
system.

   The topmost structure in a resource file is the resource header.
This is an array of words containing the size and offset within the
resource of the other structures which follow.  This information is
used by  GEM during the resource load process, and you should never
need to access it. (The resource header does not appear in the C
output file; it is generated by the RSCREATE utility if the C file is
used to recreate the resource.)

   The next structure of interest is the tree index.  This is an
array of long pointers, each of which addresses the beginning of an
object tree. Again, you wouldn't normally access this structure
directly.  The GEM  rsrc_gaddr call uses it when finding trees'
addresses.  This structure is called "rs_trindex" in the C output.

   If you look at the contents of rs_trindex you will notice that the
values are integers, instead of the pointers I described.  What has
happened is that RCS has converted the pointers to indices into the
object array. (If you actually used the C file to recreate the
resource file, then the  pointers would be regenerated by RSCREATE.)


   Now you can follow the link from rs_trindex to the objects stored
in rs_object.  Take (for instance) the second entry in rs_trindex and
count down that many lines in rs_object.  The following line (object)
should start with a -1.  This indicates that it is the root object of
a tree.  The following objects down to the next root belong to that
tree. We'll pass over the details of inter-object linkage for now,
leaving it for a later column.

   There are a number of different fields in an object, but right now
we'll concentrate on two of them: OB_TYPE and OB_SPEC.  The OB_TYPE
is the field which contains mnemonics like G_STRING and G_BOX
indicating the type of the object.  The OB_SPEC is the only field in
each object which  is a LONG - you can tell it by the L after the
number.

   What's in OB_SPEC depends on the object type, so we need to talk
about what kinds of objects are available, what you might use them
for, and finally how they use the OB_SPEC field.

   The box type objects are G_BOX, G_IBOX, and G_BOXCHAR.  A G_BOX is
an opaque rectangle, with an optional border.  It's used to create a
solid patch of color or pattern on which to place other objects.  For
instance, the background of a dialog is a G_BOX.

   A G_IBOX is a hollow box which has only a border.  (If the border
has no thickness, then the box is "invisible", hence the name.)  The
favorite use for IBOXes is to hold radio buttons.  There is also one
neat trick you can play with an IBOX.  If you have more than one
object (say an image and a string) which you would like to have
selected all at once, you can insert them in a dialog, then cover
them with an IBOX. Since the box is transparent, they will show
through.  If you now make the box selectable, clicking on it will
highlight the whole area at once!

   The G_BOXCHAR is just like a G_BOX, except that a single character
is drawn in its center.  They are mostly used as "control points":
the FULLER, CLOSER, SIZER, and arrows in GEM windows are BOXCHARs, as
are  the components of the color selection gadgets in the RCS.

   The OB_SPEC for box type objects is a packed bit array.  Its
various fields contain the background color and pattern, the border
thickness and color, and the optional character and its color.

   The string type objects are G_STRING, G_BUTTON, and G_TITLE.
G_STRINGs (in addition to being a bad pun) are for setting up static
explanatory text within dialogs.  The characters are always written
in the "system font": full size, black, with no special effects.

   We have already discussed many of the uses of G_BUTTONs.  They add
a border around the text.  The thickness of a G_BUTTON's border is
determined by what flags are set for the object.  All buttons start
out with a border thickness of one pixel.  One pixel is added if the
EXIT attribute is set, and one more is added if the DEFAULT attribute
is set.

   The G_TITLE type is a specially formatted text string used only in
the title bar of menus.  This type is needed to make sure that the
menus redraw correctly.  The Resource Construction Set automatically
handles inserting G_TITLEs, so you will seldom use them directly.

   In a resource, the OB_SPEC for all string objects is a long
pointer to a null terminated ASCII string.  The string data in the C
file is shown in the BYTE array rs_strings.  Again you will notice
that  the OB_SPECs in the C file have been converted to indices into
rs_string. To find the string which matches the object, take the
value of OB_SPEC and count down that many lines in rs_strings.  The
next line is the correct string.

   The formatted text object types are G_TEXT, G_BOXTEXT, G_FTEXT,
and G_FBOXTEXT.  G_TEXTs are a lot like strings, except that you can
specify a color, different sizes, and a positioning rule for the
text.   Since they require more memory than G_STRINGs, G_TEXTs should
be used  sparingly to draw attention to important information within
a dialog.   G_TEXTs are also useful for automatic centering of dialog
text which is  changed at run-time.  I will describe this technique
in detail later on.

   The G_BOXTEXT type adds a solid background and border to the
G_TEXT type.  These objects are occasionally used in place of
G_BUTTONs when their color will draw attention to an important
object.

   The G_FTEXT object is an editable text field.  You are able to
specify a constant "template" of characters, a validation field for
those characters which are to be typed in, and an initial value for
the input characters.  You may also select color, size, and
positioning rule for G_FTEXTs.  We'll discuss text editing at length
below.

   The G_FBOXTEXT object, as you might suspect, is the same as
G_FTEXT with the addition of background and border.  This type is
seldom used: the extra appearance details distract attention from the
text being edited.

   The OB_SPEC for a formatted text object is a pointer to yet
another type of structure: a TEDINFO.  In the C file, you will find
these in rs_tedinfo.  Take the OB_SPEC value from each text type
object and count down that many entries in rs_tedinfo, finding the
matching TEDINFO on the next line.  Each contains pointers to ASCII
strings for the template, validation, and initialization.  You can
find these strings in rs_strings, just as above.

   There are also fields for the optional background and border
details, and for the length of the template and text.  As we will see
when discussing  editing, the most important TEDINFO fields are the
TE_PTEXT pointer to  initialized text and the TE_TXTLEN field which
gives its length.

   The G_IMAGE object type is the only one of its kind.  A G_IMAGE is
a monochrome bit image.  For examples, see the images within the
various GEM alert boxes.  Note that monochrome does not necessarily
mean black.